Network Working Group M. Gahrns 

Request for Comments: 2193 Microsoft 

Category: Standards Track September 1997 
IMAP4 Mailbox Referrals 


Status of this Memo 


This document specifies an Internet standards track protocol for the 
Internet community, and requests discussion and suggestions for 


improvements. Please refer to the current edition of the "Internet 
Official Protocol Standards" (STD 1) for the standardization state 
and status of this protocol. Distribution of this memo is unlimited. 


1. Abstract 


When dealing with large amounts of users, messages and geographically 
dispersed IMAP4 [RFC-2060] servers, it is often desirable to 
distribute messages amongst different servers within an organization. 
For example an administrator may choose to store user’s personal 
mailboxes on a local IMAP4 server, while storing shared mailboxes 
remotely on another server. This type of configuration is common 
when it is uneconomical to store all data centrally due to limited 
bandwidth or disk resources. 


Mailbox referrals allow clients to seamlessly access mailboxes that 
are distributed across several IMAP4 servers. 


A referral mechanism can provide efficiencies over the alternative 
"proxy method", in which the local IMAP4 server contacts the remote 
server on behalf of the client, and then transfers the data from the 
remote server to itself, and then on to the client. The referral 
mechanism’s direct client connection to the remote server is often a 
more efficient use of bandwidth, and does not require the local 
server to impersonate the client when authenticating to the remote 
server. 


2. Conventions used in this document 


In examples, "C:" and "S:" indicate lines sent by the client and 
server respectively. 


A home server, is an IMAP4 server that contains the user’s inbox. 


A remote mailbox is a mailbox that is not hosted on the user’s home 
server. 
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A remote server is a server that contains remote mailboxes. 
A shared mailbox, is a mailbox that multiple users have access to. 


An IMAP mailbox referral is when the server directs the client to 
another IMAP mailbox. 


The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", “SHALL NOT", 
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 
document are to be interpreted as described in [RFC-2119]. 


3. Introduction and Overview 


IMAP4 servers that support this extension MUST list the keyword 
MAILBOX-REFERRALS in their CAPABILITY response. No client action is 
needed to invoke the MAILBOX-REFERRALS capability in a server. 


A MAILBOX-REFERRALS capable IMAP4 server MUST NOT return referrals 
that result in a referrals loop. 


A referral response consists of a tagged NO response and a REFERRAL 
response code. The REFERRAL response code MUST contain as an 
argument a one or more valid URLS separated by a space as defined in 
[RFC-1738]. If a server replies with multiple URLs for a particular 
object, they MUST all be of the same type. In this case, the URL MUST 
be an IMAP URL as defined in [RFC-2192]. A client that supports the 
REFERRALS extension MUST be prepared for a URL of any type, but it 
need only be able to process IMAP URLs. 


A server MAY respond with multiple IMAP mailbox referrals if there is 
more than one replica of the mailbox. This allows the implementation 
of a load balancing or failover scheme. How a server keeps multiple 
replicas of a mailbox in sync is not addressed by this document. 


If the server has a preferred order in which the client should 
attempt to access the URLs, the preferred URL SHOULD be listed in the 
first, with the remaining URLs presented in descending order of 
preference. If multiple referrals are given for a mailbox, a server 
should be aware that there are synchronization issues for a client if 
the UIDVALIDITY of the referred mailboxes are different. 


An IMAP mailbox referral may be given in response to an IMAP command 
that specifies a mailbox as an argument. 
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Example: 


A001 NO [REFERRAL IMAP://user; AUTH=*@SERVER2/REMOTE]Remote Mailbox 


NOTE: user;AUTH=* is specified as required by [RFC-2192] to avoid a 
client falling back to anonymous login. 


Remote mailboxes and their inferiors, that are accessible only via 
referrals SHOULD NOT appear in LIST and LSUB responses issued against 
the user’s home server. They MUST appear in RLIST and RLSUB 
responses issued against the user’s home server. Hierarchy referrals, 
in which a client would be required to connect to the remote server 
to issue a LIST to discover the inferiors of a mailbox are not 
addressed in this document. 


For example, if shared mailboxes were only accessible via referrals 


on a remote server, a RLIST "" "#SHARED/%" command would return the 
same response if issued against the user’s home server or the remote 
server. 


Note: Mailboxes that are available on the user’s home server do not 
need to be available on the remote server. In addition, there may be 
additional mailboxes available on the remote server, but they will 
not accessible to the client via referrals unless they appear in the 
LIST response to the RLIST command against the user’s home server. 


A MAILBOX-REFERRALS capable client will issue the RLIST and RLSUB 
commands in lieu of LIST and LSUB. The RLIST and RLSUB commands 
behave identically to their LIST and LSUB counterparts, except remote 
mailboxes are returned in addition to local mailboxes in the LIST and 
LSUB responses. This avoids displaying to a non MAILBOX-REFERRALS 
enabled client inaccessible remote mailboxes. 


4.1. SELECT, EXAMINE, DELETE, SUBSCRIBE, UNSUBSCRIBE, STATUS and APPEND 
Referrals 


An IMAP4 server MAY respond to the SELECT, EXAMINE, DELETE, 
SUBSCRIBE, UNSUBSCRIBE, STATUS or APPEND command with one or more 
IMAP mailbox referrals to indicate to the client that the mailbox is 
hosted on a remote server. 


When a client processes an IMAP mailbox referral, it will open a new 
connection or use an existing connection to the remote server so that 
it is able to issue the commands necessary to process the remote 
mailbox. 
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Example: <IMAP4 connection to home server> 


C: A001 DELETE "SHARED/FOO" 
S: A001 NO [REFERRAL IMAP://user; AUTH=*@SERVER2/SHARED/FOO] 
Remote mailbox. Try SERVER2. 


<Client established a second connection to SERVER2 and 
issues the DELETE command on the referred mailbox> 


S: * OK IMAP4revl server ready 
C: B001 AUTHENTICATE KERBEROS_V4 
<authentication exchange> 

S: B001 OK user is authenticated 


C: B002 DELETE "SHARED/FOO" 
S: B002 OK DELETE completed 


Example: <IMAP4 connection to home server> 


C: A001 SELECT REMOTE 

S: A001 NO [REFERRAL IMAP://user; AUTH=*@SERVER2/REMOTE 
IMAP: //user; AUTH=*@SERVER3/REMOTE] Remote mailbox. 
Try SERVER2 or SERVER3. 


<Client opens second connection to remote server, and 
issues the commands needed to process the items in the 
remote mailbox> 


S: * OK IMAP4revl server ready 
C: B001 AUTHENTICATE KERBEROS_V4 
<authentication exchange> 

S: B001 OK user is authenticated 


B002 SELECT REMOTE 

12 EXISTS 

1 RECENT 

OK [UNSEEN 10] Message 10 is first unseen 
OK [UIDVALIDITY 123456789] 

FLAGS (Answered Flagged Deleted Seen Draft) 
OK [PERMANENTFLAGS (Answered Deleted Seen ] 
B002 OK [READ-WRITE] Selected completed 


+ + F F HF E 


ANNNNNNA 


B003 FETCH 10:12 RFC822 
* 10 FETCH 
* 11 FETCH 
* 12 FETCH 
B003 OK FE 


NNNnNNA 


TCH Completed 


Gahrns Standards Track [Page 4] 


RFC 2193 IMAP4 Mailbox Referrals September 1997 


<Client is finished processing the REMOTE mailbox and 
wants to process a mailbox on its home server> 


C: B004 LOGOUT 
S: * BYE IMAP4revl server logging out 
S: B004 OK LOGOUT Completed 


<Client continues with first connection> 


A002 SELECT INBOX 

16 EXISTS 

2 RECENT 

OK [UNSEEN 10] Message 10 is first unseen 
OK [UIDVALIDITY 123456789] 

FLAGS (Answered Flagged Deleted Seen Draft) 
OK [PERMANENTFLAGS (Answered Deleted Seen ] 
A002 OK [READ-WRITE] Selected completed 


+ + + F HF E 


ANNNNNNA 


4.2. CREATE Referrals 


An IMAP4 server MAY respond to the CREATE command with one or more 
IMAP mailbox referrals, if it wishes to direct the client to issue 
the CREATE against another server. The server can employ any means, 
such as examining the hierarchy of the specified mailbox name, in 
determining which server the mailbox should be created on. 


Example: 


C: A001 CREATE "SHARED/FOO" 
S: A001 NO [REFERRAL IMAP://user; AUTH=*@SERVER2/SHARED/FOO] 
Mailbox should be created on remote server 


Alternatively, because a home server is required to maintain a 
listing of referred remote mailboxes, a server MAY allow the creation 
of a mailbox that will ultimately reside on a remote server against 
the home server, and provide referrals on subsequent commands that 
manipulate the mailbox. 


Example: 


C: A001 CREATE "SHARED/FOO" 
S: A001 OK CREATE succeeded 


C: A002 SELECT "SHARED/FOO" 


S: A002 NO [REFERRAL IMAP://user; AUTH=*@SERVER2/SHARED/FOO] 
Remote mailbox. Try SERVER2 
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4.3. RENAME Referrals 


An IMAP4 server MAY respond to the RENAME command with one or more 
pairs of IMAP mailbox referrals. In each pair of IMAP mailbox 
referrals, the first one is an URL to the existing mailbox name and 
the second is an URL to the requested new mailbox name. 


If within an IMAP mailbox referral pair, the existing and new mailbox 
URLs are on different servers, the remote servers are unable to 
perform the RENAME operation. To achieve the same behavior of 
server RENAME, the client MAY issue the constituent CREATE, FETCH, 
APPEND, and DELETE commands against both servers. 


If within an IMAP mailbox referral pair, the existing and new mailbox 
URLs are on the same server it is an indication that the currently 
connected server is unable to perform the operation. The client can 
simply re-issue the RENAME command on the remote server. 


Example: 


C: A001 RENAME FOO BAR 

S: A001 NO [REFERRAL IMAP://user; AUTH=* @SERVER1/FOO 
IMAP: //user; AUTH=*@SERVER2/BAR] Unable to rename mailbox 
across servers 


Since the existing and new mailbox names are on different servers, 
the client would be required to make a connection to both servers and 
issue the constituent commands require to achieve the RENAME. 


Example: 


C: A001 RENAME FOO BAR 

S: A001 NO [REFERRAL IMAP://user; AUTH=* @SERVER2/FOO 
IMAP: //user; AUTH=*@SERVER2/BAR] Unable to rename mailbox 
located on SERVER2 


Since both the existing and new mailbox are on the same remote 
server, the client can simply make a connection to the remote server 
and re-issue the RENAME command. 


4.4. COPY Referrals 


An IMAP4 server MAY respond to the COPY command with one or more IMAP 
mailbox referrals. This indicates that the destination mailbox is on 
a remote server. To achieve the same behavior of a server COPY, the 
client MAY issue the constituent FETCH and APPEND commands against 
both servers. 
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Example: 
C: A001 COPY 1 "SHARED/STUFF" 
S: A001 NO [REFERRAL IMAP://user; AUTH=* @SERVER2/SHARED/STUFF ] 
Unable to copy message(s) to SERVER2. 
5.1 RLIST command 


Arguments: reference name 
mailbox name with possible wildcards 


Responses: untagged responses: LIST 
Result: OK - RLIST Completed 
NO - RLIST Failure 
BAD - command unknown or arguments invalid 


The RLIST command behaves identically to its LIST counterpart, except 
remote mailboxes are returned in addition to local mailboxes in the 
LIST responses. 


5.2 RLSUB Command 


Arguments: reference name 
mailbox name with possible wildcards 


Responses: untagged responses: LSUB 
Result: OK - RLSUB Completed 
NO - RLSUB Failure 
BAD - command unknown or arguments invalid 


The RLSUB command behaves identically to its LSUB counterpart, except 
remote mailboxes are returned in addition to local mailboxes in the 
LSUB responses. 


6. Formal Syntax 


The following syntax specification uses the augmented Backus-Naur 
Form (BNF) as described in [ABNF]. 


list_mailbox = <list_mailbox> as defined in [RFC-2060] 
mailbox = <mailbox> as defined in [RFC-2060] 
mailbox_referral = <tag> SPACE "NO" SPACE 


<referral_response_code> (text / text_mime2) 
; See [RFC-2060] for <tag>, text and text_mime2 definition 
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referral_response_code = "[" "REFERRAL" 1* (SPACE <url>) "]" 
; See [RFC-1738] for <url> definition 


rlist "RLIST" SPACE mailbox SPACE list_mailbox 


rlsub "RLSUB" SPACE mailbox SPACE list_mailbox 


6. Security Considerations 


The IMAP4 referral mechanism makes use of IMAP URLs, and as such, 
have the same security considerations as general internet URLs [RFC- 
1738], and in particular IMAP URLs [RFC-2192]. 


with the MAILBOX-REFERRALS capability, it is potentially easier to 
write a rogue server that injects a bogus referral response that 
directs a user to an incorrect mailbox. Although referrals reduce 
the effort to write such a server, the referral response makes 
detection of the intrusion easier. 
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